v5.9.0

Compare Source

New features

P.record patterns

To match a Record<Key, Value> (an object with consistent key and value types), you can use P.record(keyPattern, valuePattern).
It takes a sub-pattern to match against the key, a sub-pattern to match against the value, and will match if all entries in the object
match these two sub-patterns.

import { match, P } from 'ts-pattern';

type Input = Record<string, number>;

const input: Input = {
  alice: 100,
  bob: 85,
  charlie: 92,
};

const output = match(input)
  .with(P.record(P.string, P.number), (scores) => `All user scores`)
  .with(P.record(P.string, P.string), (names) => `All user names`)
  .otherwise(() => '');

console.log(output);
// => "All user scores"

You can also use P.record with a single argument P.record(valuePattern), which assumes string keys:

const userProfiles = {
  alice: { name: 'Alice', age: 25 },
  bob: { name: 'Bob', age: 30 },
};

const output = match(userProfiles)
  .with(
    P.record({ name: P.string, age: P.number }),
    (profiles) => `User profiles with name and age`
  )
  .otherwise(() => 'Different format');

console.log(output);
// => "User profiles with name and age"

When using P.select in record patterns, you can extract all keys or all values as arrays:

const data = { a: 1, b: 2, c: 3 };

const keys = match(data)
  .with(P.record(P.string.select(), P.number), (keys) => keys)
  .otherwise(() => []);

const values = match(data)
  .with(P.record(P.string, P.number.select()), (values) => values)
  .otherwise(() => []);

console.log(keys); // => ['a', 'b', 'c']
console.log(values); // => [1, 2, 3]

What's Changed

• Fix: Add missing public/index.html to gif-fetcher example by @​rio-sung-ks in #​330
• set sideEffects to false to make ts-pattern tree shakable by @​timvandam in #​317
• feat(P.record): implementation by @​gvergnaud in #​332

New Contributors

• @​rio-sung-ks made their first contribution in #​330
• @​timvandam made their first contribution in #​317

Full Changelog: gvergnaud/ts-pattern@v5.8.0...v5.9.0

v5.8.0

Compare Source

TS-Pattern v5.8.0 Release Notes

New Feature: .narrow() Method for Deep Type Narrowing

.narrow() gives you fine-grained control over type narrowing of deeply nested union types during pattern matching.

What is .narrow()?

The .narrow() method allows you to explicitly narrow the input type to exclude all values that have been handled by previous patterns. This is especially useful when working with:

• Deeply nested union types
• Nullable properties at any nesting level
• Complex type structures where you need precise type information

When to Use .narrow()

By default, TS-Pattern automatically narrows top-level union types as you pattern match. However, for deeply nested types, this narrowing doesn't happen automatically to maintain optimal TypeScript performance. The .narrow() method gives you explicit control over when to perform this more computationally expensive operation.

Example Usage

type Input = { user: { role: 'admin' | 'editor' | 'viewer' } };

declare const input: Input;

const result = match(input)
  .with({ user: { role: 'admin' } }, handleAdmin)
  .narrow() // Explicitly narrow remaining cases
  .with({ user: { role: 'editor' } }, handleEditor)
  .narrow() // Narrow again if needed
  .otherwise((remaining) => {
    // remaining.user.role is now precisely 'viewer'
    handleViewer(remaining);
  });

Additional Improvements

• Improvements to release scripts
• Updated dependencies

Full Changelog: gvergnaud/ts-pattern@v5.7.1...v5.8.0

PRs

• feat: .narrow() method & typechecking perf improvement by @​gvergnaud in #​261

v5.7.1

Compare Source

Type inference bug fixes

This new release fixes the following bug in exhaustiveness checking when matching on optional properties:

type Input = { type?: 'one' } | { type: 'two' };

const f1 = (input: Input) =>
  match(input)
    .with({ type: 'one' }, () => {})
    .with({ type: 'two' }, () => {})
    .exhaustive(); // shouldn't type-check, but does 👎

const f2 = (input: Input) =>
  match(input)
    .with({ type: 'one' }, () => {})
    .with({ type: 'two' }, () => {})
    .with({ type: undefined }, () => {}) // <- the type key needs to be present.
    .exhaustive();  // shouldn't type-check, but does 👎

These two cases don't type check anymore. They fail with a NonExhaustiveError<{ type?: undefined; }>. To fix it, you should do:

type Input = { type?: 'one' } | { type: 'two' };

const f = (input: Input) =>
  match(input)
    .with({ type: 'one' }, () => {})
    .with({ type: 'two' }, () => {})
    .with({ type: P.optional(undefined) }, () => {}) // <- the type property may not be there
    .exhaustive(); // ✅

This is a purely type-level change, the runtime behavior is still the same.

What's Changed

• fix(.exhaustive): optional discriminant by @​gvergnaud in #​319

Full Changelog: gvergnaud/ts-pattern@v5.7.0...v5.7.1

v5.7.0

Compare Source

New feature

Exhaustive callback

By default, .exhaustive() will throw an error if the input value wasn't handled by any .with(...) clause. This should only happen if your types are incorrect.

It is possible to pass your own handler function as a parameter to decide what should happen if an unexpected value has been received. You can for example throw your own custom error:

match(...)
  .with(...)
  .exhaustive((unexpected: unknown) => {
    throw MyCustomError(unexpected);
  })

Or log an error and return a default value:

match<string, number>(...)
  .with(P.string, (str) => str.length)
  .exhaustive((notAString: unknown) => {
    console.log(`received an unexpected value: ${notAString}`);
    return 0;
  })

Improved narrowing for isMatching

isMatching didn't have full feature parity with match in terms of type narrowing, but now does.

What's Changed

• build(deps-dev): bump bun from 1.0.4 to 1.1.30 in /benchmarks by @​dependabot in #​303
• isMatching: improve narrowing by @​gvergnaud in #​311
• feat(exhaustive): Add support for passing a fallback function by @​gvergnaud in #​253

Full Changelog: gvergnaud/ts-pattern@v5.6.2...v5.7.0

v5.6.2

Compare Source

What's Changed

• fix(isMatching): Fix non-object patterns by @​gvergnaud in #​307

Full Changelog: gvergnaud/ts-pattern@v5.6.1...v5.6.2

v5.6.1

Compare Source

What's Changed

• fix(isMatching): Allow unknown properties in pattern by @​gvergnaud in #​305

Full Changelog: gvergnaud/ts-pattern@v5.6.0...v5.6.1

v5.6.0

Compare Source

This release contains two changes:

Typecheck pattern when using isMatching with 2 parameter.

It used to be possible to pass a pattern than could never match to isMatching. The new version checks that the provide pattern does match the value in second parameter:

type Pizza = { type: 'pizza'; topping: string };
type Sandwich = { type: 'sandwich'; condiments: string[] };
type Food = Pizza | Sandwich;

const fn = (food: Pizza | Sandwich) => {
    if (isMatching({ type: 'oops' }, food)) {
        //                  👆 used to type-check, now doesn't!
    }
}

Do not use P.infer as an inference point

When using P.infer<Pattern> to type a function argument, like in the following example:

const getWithDefault = <T extends P.Pattern>(
  input: unknown,
  pattern: T,
  defaultValue: P.infer<T> //  👈
): P.infer<T> =>
  isMatching(pattern, input) ? input : defaultValue

TypeScript could get confused and find type errors in the wrong spot:

const res = getWithDefault(null, { x: P.string }, 'oops') 
//                                     👆           👆 type error should be here
//                                 but it's here 😬

This new version fixes this problem.

What's Changed

• Improvements to P.infer and isMatching by @​gvergnaud in #​302
• build(deps-dev): bump rollup from 2.79.1 to 2.79.2 by @​dependabot in #​289

Full Changelog: gvergnaud/ts-pattern@v5.5.0...v5.6.0

v5.5.0

Compare Source

What's Changed

• Export Pattern types in package.json by @​GGomez99 in #​292 closing issue #​291

New Contributors

• @​GGomez99 made their first contribution in #​292

Full Changelog: gvergnaud/ts-pattern@v5.4.0...v5.5.0

v5.4.0

Compare Source

The main thing — Faster type checking 🚀

This release brings a significant perf improvement to exhaustiveness checking, which led to a ~16% decrease in the time to type-check the full test suite of TS-Pattern:

What's Changed

• build(deps-dev): bump braces from 3.0.2 to 3.0.3 by @​dependabot in #​273
• build(deps-dev): bump webpack from 5.91.0 to 5.94.0 in /examples/gif-fetcher by @​dependabot in #​276
• build(deps): bump serve-static and express in /examples/gif-fetcher by @​dependabot in #​283
• perf: improve type checking performance of BuildMany by @​gvergnaud in #​286
• Fixes type InvertPatternForExcludeInternal to work with readonly array by @​changwoolab in #​284

New Contributors

• @​changwoolab made their first contribution in #​284

Full Changelog: gvergnaud/ts-pattern@v5.3.1...v5.4.0

v5.3.1

Compare Source

Pattern-matching on symbol keys

Symbols used to be ignored in object patterns. They are now taken into account:

const symbolA = Symbol('symbol-a');
const symbolB = Symbol('symbol-b');

const obj = { [symbolA]: { [symbolB]: 'foo' } };
    
if (isMatching({ [symbolA]: { [symbolB]: 'bar' } }, obj)) {
   //  👆 Used to return true, now returns false!
   
   //  Since TS-Pattern wasn't reading symbols, this pattern used to be equivalent
   //  to the `{}` pattern that matches any value except null and undefined.
}

.exhaustive now throws a custom error

People have expressed the need to differentiate runtime errors that .exhaustive() might throw when the input is of an unexpected type from other runtime errors that could have happened in the same match expression. It's now possible with err instanceof NonExhaustiveError:

import { match, P, NonExhaustiveError }  from 'ts-pattern';

const fn = (input: string | number) => {
  return match(input)
    .with(P.string, () => "string!")
    .with(P.number, () => "number!")
    .exhaustive()
}

try {
  fn(null as string) // 👈 💥 
} catch (e) {
  if (e instanceof NonExhaustiveError) {
    // The input was invalid
  } else {
    // something else happened
  }
}

What's Changed

• build(deps-dev): bump braces from 3.0.2 to 3.0.3 in /examples/gif-fetcher by @​dependabot in #​262
• feat: throw custom ExhaustiveError when no matched pattern by @​adamhamlin in #​270
• Symbols as keys by @​Ayc0 in #​272

New Contributors

• @​adamhamlin made their first contribution in #​270
• @​Ayc0 made their first contribution in #​272

Full Changelog: gvergnaud/ts-pattern@v5.2.0...v5.3.1

v5.3.0

Compare Source

v5.2.0

Compare Source

The main thing

new P.string.length(n) pattern

P.string.length(len) matches strings with exactly len characters.

const fn = (input: string) =>
  match(input)
    .with(P.string.length(2), () => '🎉')
    .otherwise(() => '❌');

console.log(fn('ok')); // logs '🎉'

What's Changed

• docs: fix typo in P.when patterns code example by @​grigorischristainas in #​260
• feat: Added P.string.length by @​JUSTIVE in #​257

New Contributors

• @​grigorischristainas made their first contribution in #​260

Full Changelog: gvergnaud/ts-pattern@v5.1.2...v5.2.0

v5.1.2

Compare Source

The main thing

When combining P.nonNullable and P.nullish, you should get an exhaustive pattern matching expression, but the following case was incorrectly considered non-exhaustive:

declare const input: {
  nested: string | number | null | undefined;
};

const res = match(input)
  .with({ nested: P.nonNullable }, (x) => {/* ... */})
  .with({ nested: P.nullish }, (x) => {/* ... */})
  // should type-check
  .exhaustive();

This is fixed now.

What's Changed

• build(deps): bump postcss and react-scripts in /examples/gif-fetcher by @​dependabot in #​243
• build(deps): bump loader-utils and react-scripts in /examples/gif-fetcher by @​dependabot in #​242
• build(deps): bump jsdom and react-scripts in /examples/gif-fetcher by @​dependabot in #​241
• build(deps): bump tough-cookie and react-scripts in /examples/gif-fetcher by @​dependabot in #​240
• build(deps): bump shell-quote and react-scripts in /examples/gif-fetcher by @​dependabot in #​239
• chore: add P.map specific jsdoc for P.map by @​momentiris in #​245
• build(deps-dev): bump ejs from 3.1.9 to 3.1.10 in /examples/gif-fetcher by @​dependabot in #​249
• build(deps-dev): bump ejs from 3.1.9 to 3.1.10 by @​dependabot in #​248
• fix: exhaustive checking with nested P.nonNullable patterns by @​gvergnaud in #​252

New Contributors

• @​momentiris made their first contribution in #​245

Full Changelog: gvergnaud/ts-pattern@v5.1.1...v5.1.2

v5.1.1

Compare Source

What's Changed

• Fix(P.nonNullable): narrowing of unions of objects by @​gvergnaud in #​237

Full Changelog: gvergnaud/ts-pattern@v5.1.0...v5.1.1

v5.1.0

Compare Source

New features

P.nonNullable wildcard

Add a new P.nonNullable pattern that will match any value except null or undefined.

import { match, P } from 'ts-pattern';

const input = null;

const output = match<number | null | undefined>(input)
  .with(P.nonNullable, () => 'it is a number!')
  .otherwise(() => 'it is either null or undefined!');

console.log(output);
// => 'it is either null or undefined!'

Closes #​60 #​154 #​190 and will be a work-around for #​143.

What's Changed

• feat: Add P.nonNullable patterns by @​gvergnaud in #​229

Full Changelog: gvergnaud/ts-pattern@v5.0.8...v5.1.0